Segpay 3DSecure Implementation Guide

Simplified Process

This guide outlines a simplified approach to adding 3D Secure, an additional layer of security for online card payments, using Segpay's Merchant Plug-In (MPI). In this scenario, the MPI handles the secure authentication process, managing browser interactions and cardholder prompts, which streamlines integration for merchants. By following these instructions, you'll enhance payment security without having to manage the complex authentication process yourself.

The included JavaScript code will handle the necessary steps, making it easier for you to protect both your business and your customers from fraud. Follow the steps below to implement this simplified process on your payment page.

Step 1: Generate JWT

A JSON Web Token (JWT) must be generated in server-side code to facilitate secure communication with the Segpay MPI. JWTs are an open, industry standard (RFC-7519), method for signing and encrypting payloads between two parties.

The JWT required by the Segpay MPI utilizes shared key HS256 encryption. Please see the official JWT website https://jwt.io/ for more information and to find the library for your language of choice.

The payload of the initial JWT needed on the paypage consists of:

Copy

JSON

{
'MerchantCode': '<Segpay Provided Merchant Identifier>',
'OrderDetails': {
    'OrderNumber': '<unique order number>'
 }
}

MerchantCode is an identifier provided by Bill1st that will appear in the payload. This value will also be used as the issuer when encrypting and signing the JSON web token.

OrderNumber is a unique identifier specified by the merchant. This identifier can be of any format up to 50 alpha-numeric characters but may not be reused. This identifier is used to prevent malicious reuse of intercepted tokens.

Step 2: Insert Segpay Javascript Library

The Segpay MPI Javascript library must be inserted into the payment page:

Copy

HTML

<script src="https://secure3d.bill1st.com/js/v2/Bill1stSecure3D.js" >

Step 3: Initialize Bill1st Javascript Library

Once the library is included, it must be initialized using the MerchantCode and server-generated JWT.

This should occur before the cardholder interacts with the page, it is suggested to perform this initialization during the document.ready event.

To create a 3D secure object:

Copy

JavaScript

var Secure = new Secure3D();
Secure.logging(true);
Secure.setup( ‘<merchant code>’, ‘<jwt>’ );
Secure.enableBinDetection('CardNumberFieldID');  # where CardNumber is the ID of the field accepting the Credit Card Number

JWT Notes

An example of how to generate the JWT in php:

Copy

PHP

use Lcobucci\JWT\Builder;
use Lcobucci\JWT\Signer\Hmac\Sha256;

$jwt = (new Builder())->setIssuer($merchantcode)
->setIssuedAt($currentTime) // Configures the time that the token was issued (iat claim)
->setExpiration($currentTime + $expireTime) // Configures the expiration time of the token (exp claim). Suggest at least 15 minutes, no more than 2 hours
->set('Payload', $order) // Configures a new claim, called "Payload", containing the OrderDetails
->set('ObjectifyPayload', true) // Required to be true
->sign(new Sha256(), $secureKey) // Sign with API Key
->getToken();

The secureKey value will be provided by Segpay Support Team (along with your MerchantCode value).

Step 4: Subscribe to Events

The authentication flow relies on Javascript events to inform the caller of the results. This requires the merchant to add event handlers for two events. This should be done AFTER initialization of the library but before the cardholder has submitted payment. See Appendix A for details on the object passed into this function.

Copy

JavaScript

Secure.on('payments.validated', function(data,jwt,callback) {
// Event fired to signify the authentication flow is complete
// variable data contains authentication results
// continue with submitting payment info to merchant backend
});
Secure.on('payments.noAction', function(data) {
// Event fired to signify the card does not require further authentication
// variable data contains authentication results
// continue with submitting payment info to merchant backend
});

Step 5: Perform Authentication

The page is now ready to perform authentication using the Bill1st MPI. Prior to submitting the payment information to the Bill1st Gateway, the authentication API must be called to interact with the cardholder, typically via a button click or a form submission. This is done by creating an order object (Appendix B) with the payment information and calling Secure.do3D with that object:

Copy

JavaScript

var order ={
   "Consumer":{
      "Email1":"email@test.com",              // EITHER Email1 OR BillingAddress.Phone REQUIRED
      "BillingAddress":{
         "Phone": "8005551212",               // EITHER Email1 OR BillingAddress.Phone REQUIRED
         "FullName":"John Smith",             // EITHER FullName
         "FirstName":"John",                  // OR FirstName & LastName REQUIRED
         "LastName":"Smith",
         "Address1":"123 Main St",            // REQUIRED
         "City":"Anytown",                    // REQUIRED
         "State":"MI",                                                
         "PostalCode":"40183",                // REQUIRED
         "CountryCode":"US"                                        
      },
      "Account":{
         "AccountNumber":“4111111111111111”,  // REQUIRED 
         "ExpirationMonth":12,                // REQUIRED
         "ExpirationYear":2019,               // REQUIRED
         "CardCode":123,                      // REQUIRED
         "NameOnAccount":"JOHN SMITH"
      }
   },
   "OrderDetails":{
      "Amount":"39.99",                    // REQUIRED
      "CurrencyCode":"840"                 // REQUIRED, 3-digit ISO-4217 value
   }
 };

Secure.do3D( order );

Authorization

After authentication has occurred (events payments.validated or payments.noAction have fired), the payment information is ready for submission to the Segpay gateway for authorization of the transaction. Please see the Gateway Integration Guide for more information on the authorization gateway.

Only the 3D-Secure specifics are detailed here:

Parameter	Description
ThreeDService	Indicates the source of the data to be provided. Should be set to “CARDINAL” as the Bill1st gateway has standardized on the data as provided by the Cardinal MPI.
ThreeDSecure	Contains the “data” object from the payments.validated event in javascript. Value is JSON object that is then Base64 encoded.
SecureGrandFathered	Send a value of 1 to indicate this transaction is merchant-initiated and should be considered grandathered in (original transaction occurred before PSD regulations went into effect). Send a value of 0 or no value to indicate it is not grandathered.
SecureTransactionID	Used for merchant-initiated transactions to indicate the previous transaction where Secure 3D authentication was performed. Send the Bill1st TransactionID from a previous transaction.

Example authorization request:

Copy

XML

<?xml version="1.0" encoding="UTF-8"?>
<data>
   <auth AccountID="12345D" AccountPassword="password123" />
   <authrequest RequestID="1" AccountID="12345" CardNumber="4000000000001000" CVV="123" ExpDate="2022-12-01" Email="test@test.com" Address1="123 Main St " City="Anytown" State="IL" Zip="40155" Country="840" ProductCode="12345-100000-101" MerchantCode="DEMO20003" Amount="1.00" Currency="USD" SecureTransactionID="1485261716" SecureGrandFathered="0" ThreeDService="CARDINAL" ThreeDSecure="eyJWYWxpZGF0ZWQiOiIiLCJBY3Rpb25Db2RlIjoiTE9PS1VQIiwiQUNTVXJsIjo iIiwiUGF5bG9hZCI6IiIsIlRyYW5zYWN0aW9uSWQiOiJTNnV4OFJsMEpwUlR0WG5qQ0o5MCIsIlJl YXNvbkNvZGUiOiIiLCJSZWFzb25EZXNjIjoiIiwiQ2FyZGhvbGRlckluZm8iOiIiLCJBQ1NSZW5kZ XJpbmdUeXBlIjoiIiwiQXV0aGVudGljYXRpb25UeXBlIjoiIiwiQ2hhbGxlbmdlUmVxdWlyZWQiOi IiLCJTdGF0dXNSZWFzb24iOiIiLCJFcnJvckRlc2NyaXB0aW9uIjoiIiwiRXJyb3JOdW1iZXIiOiI wIiwiT3JkZXJJZCI6IjgwMTA4NzA0NzY5NDYxMzkiLCJUcmFuc2FjdGlvblR5cGUiOiIiLCJDYXJk QnJhbmQiOiJNQVNURVJDQVJEIiwiQ2FyZEJpbiI6IjUyMDAwMCIsIlJhd0FDU1VybCI6IiIsIlN0Z XBVcFVybCI6IiIsIkNhdnZBbGdvcml0aG0iOiIiLCJNZXJjaGFudFJlZmVyZW5jZU51bWJlciI6Ii IsIkRlY291cGxlZEluZGljYXRvciI6IiIsIlRoaXJkUGFydHlUb2tlbiI6IiIsIlRva2VuIjoiIiw iV2hpdGVMaXN0U3RhdHVzIjoiIiwiV2hpdGVMaXN0U3RhdHVzU291cmNlIjoiIiwiTmV0d29ya1Nj b3JlIjoiIiwiQXV0aG9yaXphdGlvblBheWxvYWQiOiIiLCJQYXltZW50Ijp7IkV4dGVuZGVkRGF0Y SI6eyJFbnJvbGxlZCI6IlkiLCJDQVZWIjoiWTJGeVpHbHVZV3hqYjIxdFpYSmpaV0YxZEdnPSIsIkVDSUZsYWciOiIwMiIsIlRocmVlRFNWZXJzaW9uIjoiMi4yLjAiLCJQQVJlc1N0YXR1cyI6IlkiLCJ TaWduYXR1cmVWZXJpZmljYXRpb24iOiJZIiwiWElEIjoiIiwiVUNBRkluZGljYXRvciI6IiIsIkFD U1RyYW5zYWN0aW9uSWQiOiJjMWYyMTY2My1iYTcxLTQ4YTUtYTIwMy1mYWE2Yjg4ZTY5NTgiLCJUa HJlZURTU2VydmVyVHJhbnNhY3Rpb25JZCI6IjA0Mjk2MTZjLTY0OTYtNGEyMS04NWE1LTg2OGRkMm I3NjViZCIsIkRTVHJhbnNhY3Rpb25JZCI6IjM5ZDIyZjM4LTQyMDgtNDBiZC04ODJlLWUyMTkxOTB iNGJmZSJ9fX0=" />
</data>

PSD2 and Strong Customer Authentication (SCA)

PSD2 is the Revised Payment Services Directive, a new EU regulation for electronic and non-cash payments. This version introduces the requirement for implementing Strong Customer Authentication (SCA) to make online payments more secure and reduce fraud.

SCA is required when the business and the cardholder’s bank are located within the European Economic Area (EEA). There are, however, some out-of-scope transactions and exemptions.

If you want to send parameters to disable the automatic application of exemptions by both the Segpay gateway and the acquiring/issuing banks, use the following:

SCAExemptionOverride - If this parameter is activated with a value of "Y", then no automatic exemptions will be used, and the value sent in SCAExemption will always be applied.
SCAExemption – See Table below for values and definitions:

SCAExemption Value	Description
LowValue	Transactions under €30 are exempt from SCA. If the total amount attempted on the card without strong authentication is higher than €100, or if five consecutive transactions have been conducted without SCA, SCA is required.
RiskAnalysis	The ability for a payment to be considered low risk is based on the average fraud levels of the card issuer and acquirer processing the transaction: + 0.13% to exempt transactions below €100 + 0.06% to exempt transactions below €250 + 0.01% to exempt transactions below €500
Recurring	Recurring transactions with a fixed amount are exempt beginning with the 1 st rebill. Only the initial transaction requires SCA.
TrustedBeneficiary	Customers can assign businesses to a whitelist of trusted beneficiaries. Whitelisted merchants are exempt from SCA.
MIT	Payments made with saved cards when the customer is not present in the checkout flow may qualify as merchant-initiated transactions. You need to authenticate the card on the first payment and make an agreement with the customer to charge their card at a later time. If a transaction is merchant-initiated, both fixed and variable payments will be exempt from SCA.
AnonymousCard	A transaction processed using an anonymous card can only be identified by the issuing bank, not by the customer.
CorporateCard	When the transaction is initiated by a legal person, for example, a business rather than a consumer, and it is processed through a secured dedicated payment protocol.

Example of the SCA Exemption parameters

Below is an example of the optional SCA Exemption parameters that can be sent in your auth request to the gateway:

Copy

XML

SCAExemptionOverride=”Y”
SCAExemption=”LowValue”

Issuer Mandated Authentication

During an authorization request, an issuer may decide that strong authentication is required even though it did not make that determination during the authentication/lookup phase of 3D Secure. When this occurs, the Bill1st gateway will respond with a 3009 - Strong Authentication Required response code. The merchant should detect this has occurred and enter an alternative flow for 3D Secure which forces authentication as follows:

Copy

var order ={
   "Consumer":{
      "Email1":"email@test.com",              // REQUIRED
      "BillingAddress":{
         "FullName":"John Smith",             // EITHER FullName
         "FirstName":"John",                  // OR FirstName & LastName REQUIRED
         "LastName":"Smith",
         "Address1":"123 Main St",            // REQUIRED
         "City":"Anytown",                    // REQUIRED
         "State":"MI",                                                
         "PostalCode":"40183",                // REQUIRED
         "CountryCode":"US"                                        
      },
      "Account":{
         "AccountNumber":“4111111111111111”,  // REQUIRED 
         "ExpirationMonth":12,                // REQUIRED
         "ExpirationYear":2019,               // REQUIRED
         "CardCode":123,                      // REQUIRED
         "NameOnAccount":"JOHN SMITH"
      }
   },
   "OrderDetails":{
      "Amount":"39.99",                    // REQUIRED
      "CurrencyCode":"840"                 // REQUIRED, 3-digit ISO-4217 value
   }
 };
  
// Normal flow:
// Secure.do3D( order );
  
// Authentication mandated flow:
Secure.forceAuthentication( order );

Advanced Features

If more control over the authentication process is desired, the merchant may perform additional steps to determine what authentication steps will be required BEFORE they are executed in the cardholder’s browser.

An additional parameter may be provided to the Secure.do3D method providing a callback function to run upon completion of the lookup step in the authentication process. The interpret lookup function can be used to take whatever additional steps the merchant may desire. When it is desired to continue the authentication flow, simply call Secure.continue.

For example, to perform authentication ONLY when the card is enrolled in Secure 3D 2.0 or greater:

Copy

JavaScript

Secure.do3D(order, function(lookupresponse) {
    if (lookupresponse.ThreeDVersion >= 2) {
        Secure.continue();
    }
};);

Appendix A: Order Object Full Example

Copy

JavaScript

{
    "Authorization": {
        "AuthorizeAccount": false
    },
    "Cart": [{
        "Name": "",
        "SKU": "",
        "Quantity": "",
        "Description": ""
    }],
    "Consumer": {
        "Email1": "",
        "Email2": "",
        "ShippingAddress": {
            "FullName": "",
            "FirstName": "",
            "MiddleName": "",
            "LastName": "",
            "Address1": "",
            "Address2": "",
            "Address3": "",
            "City": "",
            "State": "",
            "PostalCode": "",
            "CountryCode": "",
            "Phone1": "",
            "Phone2": ""
        },
        "BillingAddress": {
            "FullName": "",
            "FirstName": "",
            "MiddleName": "",
            "LastName": "",
            "Address1": "",
            "Address2": "",
            "Address3": "",
            "City": "",
            "State": "",
            "PostalCode": "",
            "CountryCode": "",
            "Phone1": "",
            "Phone2": ""
        },
        "Account": {
            "AccountNumber": 0,
            "ExpirationMonth": 0,
            "ExpirationYear": 0,
            "CardCode": 0,
            "NameOnAccount": ""
        }
    },
    "Options": {
        "EnableCCA": ""
    },
    "OrderDetails": {
        "OrderNumber": "",
        "Amount": "",
        "CurrencyCode": "",
        "OrderDescription": "",
        "OrderChannel": "",
        "TransactionId": ""
    },
    "Token": {
        "Token": "",
        "CardCode": 0,
        "ExpirationMonth": 0,
        "ExpirationYear": 0
    }
}

Appendix B: Event Data Object Specifications

Field	Type	Description
ActionCode	AN(30)	The resulting state of the transaction. Possible values: SUCCESS - The transaction resulted in successful authentication. NOACTION - The API calls were completed and there are no further actionable items to complete. This can indicate that the card holder is not enrolled in 3-D Secure. FAILURE - The transaction resulted in an error, typically due to the user failing to authenticate ERROR - A service level error was encountered. These are generally reserved for connectivity or API authentication issues, for example, if your JWT was incorrectly signed, or the MPI services are currently unreachable.
Authorization	Authorization Object	An object related to tokenization.
Authorization Processor
ProcessorOrderId	AN(50)	The OrderId returned back from the Processor.
ProcessorTransactionId	AN(50)	The Transaction Identifier returned back from the Processor.
ReasonCode	AN(255)	Third party error number. A non-zero value represents the error encountered while attempting the process the message request.
ReasonDescription	(AN255)	The third party description for the associated ReasonCode.
Consumer
Email1	AN(255)	Consumer's primary E-mail Address.
Email2	AN(255)	Consumer's alternate E- mail Address.
ShippingAddress	Address Object	Consumer's Shipping Address.
BillingAddress	Address Object	Consumer's Billing Address.
Account	Account Object	Consumer's Account Information.
ErrorNumber	AN(255)	Application error number. A non-zero value represents the error encountered while attempting the process the message request.
ErrorDescription	AN(255)	Application error description for the associated error number.
Payment
BillingAddress	Address	Consumers billing address. This field may not be present in every payment brand.
ExtendedData	Payment Extension Object	(See Payment Extension Object section below.)
ProcessorTransactionId	AN(255)	The Transaction Identifier returned back from the Processor.
OrderId	AN(255)	Centinel generated order identifier. Used to link multiple actions (authorize, capture, refund, etc) on a single order to a single identifier. Mod-10 compliant and unique BIN range to CardinalCommerce services.
OrderNumber	AN(255)	Order Number or transaction identifier from the Merchant website.
ShippingAddress	Address	Consumers shipping address. This field may not be present in every payment brand.
Type	AN(50)	The payment type of this transaction. Possible Values: + CCA + Paypal + Wallet + VisaCheckout + ApplePay + DiscoverWallet
ReasonDescription	AN(255)	Third party error description for the associated ReasonCode.
Validated	boolean	This value represents whether transaction was successfully or not.
Token	Token Object	The token details associated with this transaction

Payment Extension Object

Field	Type	Description
Enrolled	AN(1)	Status of Authentication ligibility. Possible Values: Y = Yes- Bank is participating in 3D Secure protocol and will return the ACSUrl N = No - Bank is not participating in 3D Secure protocol U = Unavailable - The DS or ACS is not available for authentication at the time of the request B = Bypass- Merchant authentication rule is triggered to bypass authentication in this use case NOTE: If the Enrolled value is NOT Y, then the Consumer is NOT eligible for Authentication.
CAVV	AN(40)	CAVV = Cardholder Authentication Verification Value AVV = Authentication Verification Value UCAF = Universal Cardholder Authentication Field This value should be appended to the authorization message signifying that the transaction has been successfully authenticated. This value will be encoded according to the merchant’s configuration in either Base64 encoding or Hex encoding. A Base64 encoding merchant configuration will produce values of 28 or 32 characters. A Hex encoding merchant configuration will produce values of 40 or 48 characters. The value when decoded will either be 20 bytes for CAVV or 20 or 24 bytes if the value is AAV (MasterCard UCAF).
ECIFlag	AN(40)	Electronic Commerce Indicator (ECI). The ECI value is part of the 2 data elements that indicate the transaction was processed electronically. This should be passed on the authorization transaction to the gateway/processor. See Brand ECI definitions section below
PAResStatus	AN(1)	Transaction status result identifier. Possible Values: + Y – Successful Authentication + N – Failed Authentication + U – Unable to Complete Authentication + A – Successful Attempts Transaction
SignatureVerification	AN(1)	Transaction Signature status identifier. Possible Values: + Y - Indicates that the signature of the PARes has been validated successfully and the message contents can be trusted. + N - Indicates that the PARes could not be validated. This result could be for a variety of reasons; tampering, certificate expiration, etc., and the result should not be trusted.
XID	AN(40)	Transaction identifier resulting from authentication processing. NOTE: Gateway/Processor API specification may require this value to be appended to the authorization message. This value will be encoded according to the merchant’s configuration in either Base64 encoding or Hex encoding. A Base64 encoding merchant configuration will produce values of 28 characters. A Hex encoding merchant configuration will produce values of 40 characters.
UCAFIndicator	AN(1)	Universal Cardholder Authentication Field (UCAF) Indicator value provided by the issuer. Possible Values: 0 - Non-SecureCode transaction, bypassed by the Merchant 1 - Merchant-Only SecureCode transaction 2 - Fully authenticated SecureCode transaction NOTE: This field is only returned for MasterCard transactions
ACSTransactionId	AN(36)	Unique transaction identifier assigned by the ACS to identify a single transaction.
ThreeDSSeverTransactionId	AN(36)	Unique transaction identifier assigned by the 3DS Server to identify a single transaction.
DSTrasactionID	AN(36)	Unique transaction identifier assigned by the Directory Server (DS) to identify a single transaction. NOTE: Required for Mastercard Identity Check transaction in Authorization.

Brand ECI definitions

Mastercard	Visa	Amex	JCB	Diners Club	ELO
02	05	05	05	05	05
01	06	06	06	06	06
00	07	07	07	07	07